System Designer MCP Server

CodeRabbit Pull Request Reviews

A Model Context Protocol (MCP) server that provides AI agents with tools to create, validate, and export UML system models and System Runtime bundles. Built with a tool-based approach that empowers LLMs to generate complete, executable System Runtime applications.

📚 Documentation

API Reference - Detailed API documentation for all MCP tools
System Runtime Integration Guide - Complete guide to System Runtime bundle creation
Cloudflare Deployment Guide - Deploy to Cloudflare Workers as remote MCP server
CLI Guide - Command-line interface usage and examples
Integration Guide - Platform integration instructions
Examples - Sample models and use cases
Contributing Guide - How to contribute to the project
Code of Conduct - Community guidelines and behavior expectations
Security Policy - Security vulnerability reporting and policies

Features

Core MSON Tools

create_mson_model: Create and validate MSON models from structured data
validate_mson_model: Validate MSON model consistency and completeness
generate_uml_diagram: Generate UML diagrams in PlantUML and Mermaid formats
export_to_system_designer: Export models to System Designer application format

System Runtime Tools

create_system_runtime_bundle: Convert MSON models to complete System Runtime bundles
validate_system_runtime_bundle: Validate System Runtime bundles for correctness and compatibility

Key Capabilities

✅ Tool-Based Architecture: LLMs handle understanding, server handles validation/formatting
✅ Type Safety: Comprehensive Zod schema validation for all inputs and outputs
✅ System Runtime Integration: Full support for System Runtime bundle generation and validation
✅ Bidirectional Relationships: Automatic bidirectional relationship creation
✅ Multiple Inheritance: Support for classes implementing multiple interfaces
✅ Multiple UML Formats: Support for both PlantUML and Mermaid diagram generation
✅ System Designer Integration: Direct export to System Designer macOS application
✅ Comprehensive Testing: 46 tests with 302 expect() calls covering all functionality
✅ Critical Bug Fixes: Resolved SDMCP-001 through SDMCP-005 (property preservation, ID management, validation consistency)
✅ Streamable HTTP Transport: Modern MCP protocol (2025-03-26 specification)
✅ Stateless Operation: Each request creates new server instance
✅ Single Endpoint: Single /mcp endpoint handles all operations
✅ Workers Optimized: Stateless design perfect for Cloudflare Workers

Installation

Prerequisites

Bun JavaScript runtime
Node.js compatibility through Bun

Setup

# Clone the repository git clone https://github.com/chevyphillip/system-designer-mcp.git cd system-designer-mcp # Install dependencies bun install # Build the project bun run build # Run tests bun test

Quick Start

Deployment Options

The System Designer MCP Server can run in two modes:

Local Mode (stdio transport)

Start the local server:

bun run dev

Remote Mode (Cloudflare Workers)

Deploy as a remote MCP server accessible over HTTP with SSE transport:

# Test locally with Wrangler bun run dev:worker # Deploy to Cloudflare Workers bunx wrangler login bun run deploy

Your MCP server will be available at:

https://system-designer-mcp.<your-subdomain>.workers.dev

Note: Replace <your-subdomain> with your actual Cloudflare Workers subdomain.

Key Features:

✅ SSE (Server-Sent Events) transport for remote access
✅ No authentication required (configurable)
✅ All 6 MCP tools available
✅ Returns JSON data directly (no file system)
✅ Automatic session management
✅ CORS support for web clients

See

Usage Examples

Example tool usage:

// Create a MSON model const model = await mcpClient.callTool('create_mson_model', { name: 'Student Management System', type: 'class', description: 'A system for managing students and courses', entities: [ { id: 'student', name: 'Student', type: 'class', attributes: [ { name: 'id', type: 'string', visibility: 'private' }, { name: 'name', type: 'string', visibility: 'public' }, ], methods: [{ name: 'enroll', returnType: 'void', visibility: 'public' }], }, ], relationships: [], }); // Generate UML diagram const diagram = await mcpClient.callTool('generate_uml_diagram', { model: model.content[1].json, format: 'plantuml', }); // Export to System Designer const exported = await mcpClient.callTool('export_to_system_designer', { model: model.content[1].json, filePath: './student_system.json', }); // Create System Runtime bundle const bundle = await mcpClient.callTool('create_system_runtime_bundle', { model: model.content[1].json, version: '1.0.0', }); // Validate System Runtime bundle const validation = await mcpClient.callTool('validate_system_runtime_bundle', { bundle: bundle.content[2].text, // JSON bundle from previous step });

CLI Usage

The server includes a CLI tool for testing and model management:

# Test System Designer integration bun run src/cli.ts test-integration # Export a test model bun run src/cli.ts export-model MyModel "Test model description" # Show configuration bun run src/cli.ts config

See the CLI Guide for detailed usage instructions.

Example MSON Model Structure

{ "id": "student_system", "name": "Student Management System", "type": "class", "description": "A system for managing students and courses", "entities": [ { "id": "student", "name": "Student", "type": "class", "attributes": [ { "name": "id", "type": "string", "visibility": "private" }, { "name": "name", "type": "string", "visibility": "public" } ], "methods": [ { "name": "enroll", "parameters": [ { "name": "course", "type": "Course" } ], "returnType": "void", "visibility": "public" } ] } ], "relationships": [ { "id": "enrollment", "from": "student", "to": "course", "type": "association", "multiplicity": { "from": "1", "to": "0..*" }, "name": "enrolls in" } ] }

Tool Reference

For detailed API documentation, see the API Reference.

Available Tools

create_mson_model - Create and validate MSON models from structured data with automatic ID generation and relationship mapping
validate_mson_model - Validate MSON model consistency and completeness with detailed error messages and relationship validation
generate_uml_diagram - Generate UML diagrams in PlantUML and Mermaid formats
export_to_system_designer - Export models to System Designer application format
create_system_runtime_bundle - Convert MSON models to complete System Runtime bundles with schemas, models, types, behaviors, and components
validate_system_runtime_bundle - Validate System Runtime bundles for correctness and compatibility

Platform Integration

The server can be integrated with various platforms:

Claude Desktop - Native MCP integration
VS Code - Extension development support
Web Applications - React/Node.js integration
CLI Tools - Command-line interface

See the Integration Guide for detailed setup instructions.

Architecture

Modular Structure

The codebase follows SOLID principles with clear separation of concerns:

src/types.ts - TypeScript type definitions for MSON models
src/schemas.ts - Zod validation schemas for all data structures
src/tools.ts - MCP tool registration using modern SDK patterns
src/index.ts - Local MCP server with stdio transport (Node.js/Bun)
src/worker.ts - Remote MCP server with SSE transport (Cloudflare Workers)
src/cli.ts - Command-line interface for testing and integration
src/integration/ - System Designer app integration
src/transformers/ - MSON to System Runtime transformation logic
src/validators/ - System Runtime bundle validation logic

Modern MCP SDK Patterns

The server uses the modern MCP TypeScript SDK (v1.18.2) patterns:

server.registerTool() - Modern tool registration API (not legacy server.tool())
Zod Input Schemas - Type-safe input validation with Zod schema shapes
Title Metadata - Each tool includes a title field for better UX
Type Inference - Handler methods use Zod-inferred types for parameters

Tool-Based Approach

This server uses a tool-based architecture that:

Empowers LLMs: The LLM handles understanding requirements and creating structured data
Validates Input: Server validates structured input using comprehensive Zod schemas
Processes Efficiently: Simple, fast processing without complex parsing logic
Exports Flexibly: Multiple output formats for different use cases

Benefits Over Parser-Based Approaches

Simplicity: No complex NLP parsing to maintain
Flexibility: Works with any domain the LLM understands
Reliability: Fewer moving parts, less error-prone
Performance: Faster validation and processing
Extensibility: Easy to add new tools and features

Development

Running Tests

# Run all tests bun test # Run tests in watch mode bun test --watch

Building

# Build for production bun run build # Start production server bun start

Code Structure

src/ ├── types.ts # TypeScript type definitions for MSON models ├── schemas.ts # Zod validation schemas for all data structures ├── tools.ts # MCP tool registration using modern SDK patterns ├── index.ts # Local MCP server (stdio transport) ├── worker.ts # Remote MCP server (SSE transport for Workers) ├── cli.ts # Command-line interface ├── integration/ │ └── system-designer.ts # System Designer app integration ├── transformers/ │ └── system-runtime.ts # MSON to System Runtime transformation └── validators/ └── system-runtime.ts # System Runtime bundle validation test/ └── tool-based.test.ts # Comprehensive test suite docs/ ├── API-REFERENCE.md # Detailed API documentation ├── CLI-GUIDE.md # CLI usage guide ├── INTEGRATION-GUIDE.md # Platform integration guide └── SYSTEM-RUNTIME-INTEGRATION-GUIDE.md # System Runtime guide examples/ ├── banking-system.json # Sample banking system model ├── banking-system-plantuml.puml # PlantUML output example ├── banking-system-mermaid.md # Mermaid output example └── README.md # Example documentation CLOUDFLARE_DEPLOYMENT.md # Cloudflare Workers deployment guide test-worker.sh # Automated testing script for Workers wrangler.toml # Cloudflare Workers configuration

Integration with System Designer

The server exports models in a format compatible with the System Designer macOS application:

File Export: Models are saved as JSON files
Automatic Integration: Files can be imported directly into System Designer
Format Compatibility: Uses MSON (Metamodel JavaScript Object Notation) format

Recent Changes & Improvements

Latest Updates (v1.0.0)

🎯 Critical Bug Fixes (SDMCP-001-005): Resolved property preservation, ID mapping, validation consistency, and bundle compatibility issues
🔧 Enhanced Error Messages: Added detailed, actionable error messages with specific fix suggestions and examples
🛡️ Relationship Validation: Proactive validation prevents orphaned references with clear guidance
🔄 Flexible Input Handling: Support for both 'properties' and 'attributes' in entity definitions
📋 Comprehensive Bug Reports: Detailed documentation of all issues and resolutions in docs/BUG_REPORTS.md
🆕 System Runtime Tools: Added complete System Runtime bundle creation and validation functionality

Previous Features

🏗️ Modular Architecture: Complete refactoring for SOLID principles compliance
🧪 Enhanced Testing: 46 tests with 302 assertions covering all functionality including edge cases
🚀 Cloudflare Workers Support: Remote MCP server deployment with modern JSON-RPC transport
🔄 Modern MCP SDK: Updated to latest MCP TypeScript SDK (v1.18.2) patterns
📊 Documentation: Complete API reference, integration guides, and deployment documentation

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

Setting up the development environment
Running tests and code quality checks
Code style guidelines
Submitting pull requests
Reporting issues

License

MIT License - see LICENSE file for details.

Acknowledgments

Model Context Protocol (MCP) for the tool integration framework
System Designer for the target macOS application
Zod for type-safe validation
Bun for the fast JavaScript runtime