System Designer MCP Server

[](https://mseep.ai/app/chevyphillip-system-designer-mcp) # System Designer MCP Server  [](https://mseep.ai/app/5d7ccf51-18ca-400a-a973-b132fa11ab92) 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](./docs/API-REFERENCE.md) - Detailed API documentation for all MCP tools - [System Runtime Integration Guide](./docs/SYSTEM-RUNTIME-INTEGRATION-GUIDE.md) - Complete guide to System Runtime bundle creation - [Cloudflare Deployment Guide](./CLOUDFLARE_DEPLOYMENT.md) - Deploy to Cloudflare Workers as remote MCP server - [CLI Guide](./docs/CLI-GUIDE.md) - Command-line interface usage and examples - [Integration Guide](./docs/INTEGRATION-GUIDE.md) - Platform integration instructions - [Examples](./examples/README.md) - Sample models and use cases - [Contributing Guide](./CONTRIBUTING.md) - How to contribute to the project - [Code of Conduct](./CODE_OF_CONDUCT.md) - Community guidelines and behavior expectations - [Security Policy](./SECURITY.md) - 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](https://bun.sh/) JavaScript runtime - Node.js compatibility through Bun ### Setup ```bash # 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 ```bash # 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 ``` ## Deployment Options The System Designer MCP Server can run in two modes: ### Local Mode (stdio transport) **Start the local server**: ```bash bun run dev ``` ### Remote Mode (Cloudflare Workers) Deploy as a remote MCP server accessible over HTTP with SSE transport: ```bash # 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: ```text 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 [CLOUDFLARE_DEPLOYMENT.md](./CLOUDFLARE_DEPLOYMENT.md) for detailed deployment instructions.** ## Usage Examples **Example tool usage**: ```javascript // 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: ```bash # 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](./docs/CLI-GUIDE.md) for detailed usage instructions. ### Example MSON Model Structure ```json { "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](./docs/API-REFERENCE.md). ### 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](./docs/INTEGRATION-GUIDE.md) 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: 1. **`server.registerTool()`** - Modern tool registration API (not legacy `server.tool()`) 2. **Zod Input Schemas** - Type-safe input validation with Zod schema shapes 3. **Title Metadata** - Each tool includes a `title` field for better UX 4. **Type Inference** - Handler methods use Zod-inferred types for parameters ### Tool-Based Approach This server uses a tool-based architecture that: 1. **Empowers LLMs**: The LLM handles understanding requirements and creating structured data 2. **Validates Input**: Server validates structured input using comprehensive Zod schemas 3. **Processes Efficiently**: Simple, fast processing without complex parsing logic 4. **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 ```bash # Run all tests bun test # Run tests in watch mode bun test --watch ``` ### Building ```bash # Build for production bun run build # Start production server bun start ``` ### Code Structure ```text 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: 1. **File Export**: Models are saved as JSON files 2. **Automatic Integration**: Files can be imported directly into System Designer 3. **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](./CONTRIBUTING.md) 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](./LICENSE) file for details. ## Acknowledgments - [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) for the tool integration framework - [System Designer](https://systemdesigner.io/) for the target macOS application - [Zod](https://zod.dev/) for type-safe validation - [Bun](https://bun.sh/) for the fast JavaScript runtime