MCP WebDev Server 🚀

Comprehensive Svelte + shadcn-svelte + Routify development server with modular orchestrator system

A powerful MCP (Model Context Protocol) server that integrates shadcn-svelte, Svelte 5, and Routify for rapid website building, plus a complete modular orchestrator system for complex application state management.

🏗️ Architecture Overview

This repository contains two major systems:

1. MCP WebDev Server (/src/)

Strategic Core 8 MCP functions for rapid Svelte development:

Core Functions (6):

• generate_component - Create Svelte components with shadcn-svelte integration
• generate_page - Generate complete pages with routing
• scaffold_project - Create full project structure
• create_route - Set up Routify routes with parameters
• generate_theme - Create consistent design systems
• list_templates - Browse available templates and patterns

Strategic Functions (2):

• search_examples - Find relevant code examples and documentation
• compose_patterns - Build complex UI patterns from multiple components

2. Modular Orchestrator System (/orchestrator-modules/)

Pluggable module system for sophisticated Svelte applications:

Core Foundation:

• @orchestrator/core - Singleton state management, hooks system (always included)

Plugin Modules:

• @orchestrator/websocket - Real-time WebSocket integration
• @orchestrator/api - REST API management with retry logic
• @orchestrator/workflow - Visual workflow engine with node execution
• @orchestrator/files - File processing (JSON, YAML, CSV) and uploads
• @orchestrator/state-ui - State visualization and management interface
• @orchestrator/hooks-ui - Hook management and debugging interface

🚀 Quick Start

Install as MCP Server

# Install the MCP server globally
npm install -g @theagencyinstitute/mcp-webdev

# Add to your Claude Desktop config
claude mcp add --scope user webdev -- mcp-webdev-server

Use the Orchestrator System

// Minimal setup (just state management)
import { Orchestrator } from '@orchestrator/core';

const app = Orchestrator.getInstance({
  debug: true,
  persistence: { type: 'localStorage', prefix: 'my-app' }
});

app.setState('user', { name: 'John', theme: 'dark' });

// Full-featured real-time dashboard
import { Orchestrator } from '@orchestrator/core';
import { WebSocketModule } from '@orchestrator/websocket';
import { ApiModule } from '@orchestrator/api';
import { StateUIModule } from '@orchestrator/state-ui';

const dashboard = Orchestrator.getInstance()
  .use(WebSocketModule, { url: 'ws://localhost:8080' })
  .use(ApiModule, { baseUrl: 'https://api.example.com' })
  .use(StateUIModule);

📦 What's Included

MCP WebDev Server Features:

✅ Complete shadcn-svelte Integration (40+ components)

• Alert, Avatar, Badge, Button, Card, Checkbox, Dialog, Dropdown, Input, Select, Table, Tooltip, etc.
• Full component metadata with props, variants, and examples

✅ Svelte 5 Runes Support

• $state, $derived, $effect, $props integration
• Modern reactive patterns and type safety

✅ Routify File-based Routing

• Dynamic routes with parameters
• Layout systems and navigation
• Route guards and meta handling

✅ Advanced Code Generation

• Component composition patterns (Auth, Dashboard, E-commerce)
• Theme generation with CSS variables
• TypeScript integration throughout

Orchestrator System Features:

✅ Always-Present State Management

• Svelte stores integration
• Persistence (localStorage/sessionStorage/memory)
• State snapshots and history

✅ Powerful Hook System

• Lifecycle events (beforeStateUpdate, afterStateUpdate)
• Module installation/uninstallation hooks
• Custom event system

✅ Visual Workflow Engine

• Drag-drop node-based workflows
• Trigger/Action/Condition/Transform nodes
• Topological execution with logging

✅ Real-time Integration

• WebSocket auto-reconnection
• Message routing to state
• Connection status tracking

✅ File Processing

• JSON, YAML, CSV parsing
• Custom file processors
• Drag-drop uploads with validation

📁 Project Structure

mcp_webdev/
├── src/                          # MCP WebDev Server
│   ├── index.ts                  # Main server entry point
│   ├── integrations/             # shadcn-svelte integration
│   ├── services/                 # Code generation services
│   ├── templates/                # Component and page templates
│   └── generators/               # File generators
├── orchestrator-modules/         # Modular Orchestrator System
│   ├── core/                     # Core orchestrator (state + hooks)
│   ├── websocket/               # WebSocket module
│   ├── api/                     # API integration module
│   ├── workflow/                # Workflow engine module
│   ├── files/                   # File processing module
│   ├── state-ui/                # State management UI
│   ├── hooks-ui/                # Hook debugging UI
│   └── examples/                # Usage examples
├── dist/                        # Compiled output
└── README.md                    # This file

🎯 Usage Examples

Example 1: Minimal App (Just State Management)

import { Orchestrator } from '@orchestrator/core';

const app = Orchestrator.getInstance({
  persistence: { type: 'localStorage', prefix: 'minimal-app' }
});

app.setState('user', { name: 'John', preferences: { theme: 'dark' } });
app.addHook('afterStateUpdate', (context) => {
  console.log(`State updated: ${context.data.key}`, context.data.value);
});

Example 2: Real-time Dashboard

import { Orchestrator } from '@orchestrator/core';
import { WebSocketModule } from '@orchestrator/websocket';
import { ApiModule } from '@orchestrator/api';

const dashboard = Orchestrator.getInstance()
  .use(WebSocketModule, { 
    url: 'ws://localhost:8080/metrics',
    autoReconnect: true 
  })
  .use(ApiModule, { 
    baseUrl: 'https://api.metrics.com',
    timeout: 15000 
  });

dashboard.addHook('websocketMessage', async (context) => {
  const { data } = context.data;
  if (data.type === 'metrics') {
    dashboard.setState('metrics.realtime', data.payload);
  }
});

dashboard.connectWebSocket();

Example 3: E-commerce with Workflows

import { Orchestrator } from '@orchestrator/core';
import { ApiModule } from '@orchestrator/api';
import { FilesModule } from '@orchestrator/files';
import { WorkflowModule } from '@orchestrator/workflow';

const ecommerce = Orchestrator.getInstance()
  .use(ApiModule, { baseUrl: 'https://api.shop.com' })
  .use(FilesModule, { allowedTypes: ['csv', 'json'] })
  .use(WorkflowModule);

// Order processing workflow
const orderWorkflow = {
  id: 'order-processing',
  name: 'Order Processing',
  nodes: [
    { id: 'validate-cart', type: 'condition' },
    { id: 'create-order', type: 'action' },
    { id: 'send-confirmation', type: 'action' }
  ]
  // ... connections and config
};

ecommerce.saveWorkflow(orderWorkflow);

🚀 Available MCP Functions - Strategic Core 8

🛠️ Development

Prerequisites

• Node.js 18+
• TypeScript 5+
• Svelte 5

Setup Development Environment

git clone https://github.com/TheAgencyInstitute/mcp_webdev.git
cd mcp_webdev
npm install

# Build the MCP server
npm run build

# Test the server
npm test

# Development mode
npm run dev

Testing MCP Functions

# Test MCP server connection
node test-server.js

# Test individual functions
npm run test:generate-component
npm run test:scaffold-project

Building Orchestrator Modules

cd orchestrator-modules/core
npm run build

cd ../websocket
npm run build

# ... etc for other modules

🔧 Integration

Works seamlessly with:

• ✅ Svelte 4/5 & SvelteKit
• ✅ shadcn-svelte (40+ components)
• ✅ Routify (file-based routing)
• ✅ Tailwind CSS & TypeScript
• ✅ Vite build system

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript strict mode
• Add tests for new functionality
• Update documentation for API changes
• Use conventional commit messages

📄 License

MIT License - see LICENSE for details.

🚀 Roadmap

• MCP Server Enhancements

  • SvelteKit integration
  • TailwindCSS optimization
  • Component testing generation
  • Storybook integration

• Orchestrator Modules

  • Database integration module
  • Authentication module
  • Notification system module
  • Analytics tracking module

• Developer Experience

  • Visual workflow designer UI
  • Module marketplace
  • CLI scaffolding tools
  • VS Code extension

❤️ Acknowledgments

• Based on the battle-tested coderific orchestrator architecture
• Integrates the excellent shadcn-svelte component library
• Built for the Svelte 5 runes system
• Powered by Routify file-based routing

Built with ❤️ by The Agency Institute

Empowering rapid, modular, and scalable Svelte application development