System Designer MCP Server

# System Designer MCP Server Examples This directory contains **authentic example outputs** from the System Designer MCP Server. All examples were generated by actually running the MCP server tools, not manually created. This ensures they represent real, working outputs that users can expect when using the server. ## 🎯 Authenticity Guarantee Every file in this directory was generated using the `scripts/generate-examples.ts` script, which: 1. Loads MSON model definitions 2. Calls the actual MCP server tool handlers 3. Validates all outputs 4. Saves the results to files **No manual editing** - All outputs are direct results from the MCP server tools. ## 📚 Available Examples ### 1. Student Management System (Simple) A simple educational example demonstrating basic class relationships. **Natural Language Prompt:** > "Create a simple student management system with Student and Course entities. Students can enroll in multiple courses, and courses can have multiple students enrolled. Include appropriate attributes and methods." **Generated Files:** - **`student-system.json`** - MSON model definition (input) - **`student-system-plantuml.puml`** - PlantUML class diagram (output) - **`student-system-mermaid.md`** - Mermaid class diagram (output) - **`student-system-export.json`** - System Designer export format (output) - **`student-system-runtime-bundle.json`** - System Runtime bundle (output) **Features:** - 2 entities (Student, Course) - 1 relationship (Student enrolls in Course) - Basic attributes and methods - Association with multiplicity ### 2. Banking System (Complex) A comprehensive banking system demonstrating advanced modeling capabilities. **Natural Language Prompt:** > "Create a comprehensive banking system with Customer, Account, Transaction, Loan, Branch, Employee, Address, and LoanApplication entities. Include realistic relationships showing customers owning accounts, accounts having transactions, branches employing staff, and loan application workflows. Add appropriate methods for banking operations." **Generated Files:** - **`banking-system.json`** - MSON model definition (input) - **`banking-system-plantuml.puml`** - PlantUML class diagram (output) - **`banking-system-mermaid.md`** - Mermaid class diagram (output) - **`banking-system-export.json`** - System Designer export format (output) - **`banking-system-runtime-bundle.json`** - System Runtime bundle (output) **Features:** - 8 entities (Customer, Account, Transaction, Loan, Branch, Employee, Address, LoanApplication) - 11 relationships with various multiplicities - Complex business logic and workflows - Multiple relationship types (association, composition, aggregation) - 36 methods across all entities - 49 attributes with proper visibility modifiers ## System Architecture ### Core Entities (8) 1. **Customer** - Bank customers with personal information and financial activities 2. **Account** - Financial accounts with balance management and transactions 3. **Transaction** - Individual financial transactions between accounts 4. **Loan** - Loan products with terms and payment management 5. **Branch** - Physical bank locations with staff and customers 6. **Employee** - Bank staff who process transactions and approve loans 7. **Address** - Address information for customers and branches 8. **LoanApplication** - Loan request workflow with approval process ### Relationships (11) - **Customer → Account** (1:0..\*) - Customers own multiple accounts - **Account → Transaction** (1:0..\*) - Accounts have multiple transactions - **Customer → Loan** (1:0..\*) - Customers have multiple loans - **Customer → LoanApplication** (1:0..\*) - Customers submit loan applications - **Branch → Customer** (1:0..\*) - Branches serve multiple customers - **Branch → Employee** (1:0..\*) - Branches employ multiple staff - **Employee → Branch** (1:1) - Employees work at one branch - **Customer → Address** (1:1) - Customers have one address - **Branch → Address** (1:1) - Branches have one address - **LoanApplication → Employee** (1:0..1) - Applications approved by employees - **LoanApplication → Loan** (1:0..1) - Applications result in loans ### Key Features #### Customer Management - Personal information management - Account opening and closing - Loan applications - Fund transfers between accounts #### Account Management - Deposit and withdrawal operations - Balance inquiries - Transaction history - Interest calculation - Account closure #### Transaction Processing - Transaction validation and processing - Detailed transaction tracking - Status management - Account-to-account transfers #### Loan Management - Loan application workflow - Payment processing - Balance tracking - Refinancing options #### Branch Operations - Customer service - Staff management - Branch operations - Address management ## 🔧 How These Examples Were Generated All examples in this directory were generated using the System Designer MCP Server with modern SDK patterns. The generation process ensures **100% authenticity** - every file is a real output from the MCP server tools. ### Generation Process 1. **Model Creation**: Using `create_mson_model` tool with Zod-validated input schemas 2. **Validation**: Using `validate_mson_model` tool to ensure consistency 3. **PlantUML Generation**: Using `generate_uml_diagram` tool with `format: 'plantuml'` 4. **Mermaid Generation**: Using `generate_uml_diagram` tool with `format: 'mermaid'` 5. **System Designer Export**: Using `export_to_system_designer` tool for app integration 6. **System Runtime Bundle**: Using `create_system_runtime_bundle` tool for runtime framework 7. **Bundle Validation**: Using `validate_system_runtime_bundle` tool to verify correctness ### Regenerating Examples You can regenerate all examples using the included script: ```bash bun run scripts/generate-examples.ts ``` This script: - ✅ Loads existing MSON model definitions - ✅ Calls actual MCP server tool handlers (not mocks) - ✅ Validates all outputs before saving - ✅ Generates all 5 output formats for each example - ✅ Demonstrates modern `server.registerTool()` API usage - ✅ Uses Zod schema validation throughout - ✅ Exercises all 6 MCP tools in action ### What Makes These Examples Authentic? 1. **Direct Tool Calls**: The script calls the same handler methods that the MCP server uses 2. **No Manual Editing**: Files are written directly from tool outputs 3. **Validation Gates**: All outputs pass through validation before being saved 4. **Reproducible**: Running the script again produces identical results 5. **Version Controlled**: Changes to tool outputs are tracked in git ## 📖 Using the Examples ### 1. With MCP Client (LLM Integration) When using an LLM with MCP support, provide natural language prompts like those in `PROMPTS.md`: ``` User: "Create a student management system with Student and Course entities..." LLM: [Uses create_mson_model tool] [Uses validate_mson_model tool] [Uses generate_uml_diagram tool] [Uses create_system_runtime_bundle tool] ``` ### 2. Programmatic Usage ```javascript // Create a model const model = await mcpClient.callTool('create_mson_model', { name: 'Student Management System', type: 'class', entities: [ /* ... */ ], relationships: [ /* ... */ ], }); // Validate the model const validation = await mcpClient.callTool('validate_mson_model', { model: model.content[1].json, }); // Generate UML diagram const diagram = await mcpClient.callTool('generate_uml_diagram', { model: model.content[1].json, format: 'plantuml', // or 'mermaid' }); // Create System Runtime bundle const bundle = await mcpClient.callTool('create_system_runtime_bundle', { model: model.content[1].json, version: '1.0.0', }); // Export to System Designer const exported = await mcpClient.callTool('export_to_system_designer', { model: model.content[1].json, filePath: './output.json', }); ``` ### 3. Visualizing Diagrams **With PlantUML:** ```bash # Generate PNG from PlantUML plantuml student-system-plantuml.puml plantuml banking-system-plantuml.puml ``` **With Mermaid:** Copy the Mermaid code into any Mermaid-enabled platform: - GitHub/GitLab markdown - Mermaid Live Editor (<https://mermaid.live>) - Notion, Obsidian, etc. ### 4. Using System Runtime Bundles The System Runtime bundles can be imported directly into applications using the System Runtime framework: ```javascript import runtime from 'system-runtime'; // Load the bundle const bundle = require('./examples/student-system-runtime-bundle.json'); runtime.bundle(bundle); // Use the generated components const Student = runtime.require('Student'); const student = new Student({ id: '123', name: 'John Doe', email: 'john@example.com', }); ``` ## 📊 Example Statistics ### Student System (Simple) - **Entities**: 2 (Student, Course) - **Relationships**: 1 - **Methods**: 2 - **Attributes**: 6 - **Complexity**: Low - **Use Case**: Educational, introductory example ### Banking System (Complex) - **Entities**: 8 (Customer, Account, Transaction, Loan, Branch, Employee, Address, LoanApplication) - **Relationships**: 11 - **Methods**: 36 - **Attributes**: 49 - **Complexity**: Medium-High - **Use Case**: Enterprise, production-ready example ### Combined Statistics - **Total Examples**: 2 - **Total Entities**: 10 - **Total Relationships**: 12 - **Total Methods**: 38 - **Total Attributes**: 55 - **Total Generated Files**: 10 (5 per example) - **Model Type**: Class Diagrams - **Output Formats**: 5 (MSON JSON, PlantUML, Mermaid, System Designer Export, System Runtime Bundle) ## ✅ Validation & Quality Assurance All examples have been validated using the System Designer MCP Server tools: ### MSON Model Validation (`validate_mson_model`) - ✅ All entity IDs are unique - ✅ All relationship references are valid - ✅ No orphaned relationships - ✅ Proper multiplicity definitions - ✅ Valid entity types and attributes - ✅ Consistent method signatures - ✅ Appropriate visibility modifiers ### System Runtime Bundle Validation (`validate_system_runtime_bundle`) - ✅ All schema references are valid - ✅ Inheritance chains are correct - ✅ Method signatures match schemas - ✅ Component types are properly defined - ✅ No circular dependencies - ✅ All required fields are present ## 📤 Export Options Each example model can be exported to multiple formats using the MCP server tools: ### Available Formats 1. **MSON JSON** (`*.json`) - Native format for the MCP server - Input format for all other tools - Human-readable and version-controllable 2. **PlantUML** (`*-plantuml.puml`) - Industry-standard UML diagram format - Can be rendered to PNG, SVG, or other image formats - Integrates with documentation tools 3. **Mermaid** (`*-mermaid.md`) - Web-compatible diagram format - Renders in GitHub, GitLab, Notion, etc. - Interactive and embeddable 4. **System Designer Export** (`*-export.json`) - Native format for System Designer macOS app - Can be imported and edited visually - Supports round-trip editing 5. **System Runtime Bundle** (`*-runtime-bundle.json`) - Complete runtime package for System Runtime framework - Includes schemas, models, types, behaviors, and components - Ready for deployment in applications ### Format Comparison | Format | Use Case | Editable | Visual | Runtime | | --------------- | --------------- | -------- | ------ | ------- | | MSON JSON | Source of truth | ✅ | ❌ | ❌ | | PlantUML | Documentation | ❌ | ✅ | ❌ | | Mermaid | Web docs | ❌ | ✅ | ❌ | | System Designer | Visual editing | ✅ | ✅ | ❌ | | Runtime Bundle | Deployment | ❌ | ❌ | ✅ | ## 💬 Natural Language Prompts Each example was created from a natural language prompt that an LLM user might provide. These prompts are documented in `PROMPTS.md` and demonstrate how to effectively communicate modeling requirements to an LLM. ### Example Prompt Structure A good prompt should include: 1. **Domain Context**: What system are you modeling? 2. **Key Entities**: What are the main objects/classes? 3. **Relationships**: How do entities relate to each other? 4. **Attributes**: What data does each entity store? 5. **Methods**: What operations can be performed? 6. **Constraints**: Any business rules or multiplicities? ### See Also - **`PROMPTS.md`** - Complete collection of prompts used to generate these examples - Includes prompts for Student System, Banking System, and E-Commerce System - Shows best practices for prompt engineering with MCP servers ## 🔗 Integration with System Designer App The System Designer export format allows seamless integration with the System Designer macOS application: 1. Open System Designer app 2. Import `*-export.json` file (e.g., `banking-system-export.json`) 3. The model appears as a complete, editable class diagram 4. Make visual changes using the app's interface 5. Export back to MSON format if changes are made 6. Re-run MCP tools to regenerate diagrams and bundles ## Extending the Model ### Additional Entities to Consider - **Card** - Debit/Credit card management - **ATM** - ATM transactions and locations - **BillPayment** - Bill payment services - **Investment** - Investment accounts and portfolios - **Insurance** - Insurance products - **Alert** - Account alerts and notifications ### Additional Features - Multi-currency support - International banking - Mobile banking integration - API endpoints for web banking - Audit and compliance features ## Technical Details ### Modern MCP SDK Patterns These examples demonstrate the modern MCP TypeScript SDK (v1.18.2) patterns: - **`server.registerTool()`** - Modern tool registration API - **Zod Input Schemas** - Type-safe input validation - **Title Metadata** - Enhanced UX with tool titles - **Type Inference** - Zod-inferred types for parameters ### Modular Architecture The examples were generated using a modular codebase structure: - **`src/types.ts`** - TypeScript type definitions - **`src/schemas.ts`** - Zod validation schemas - **`src/tools.ts`** - Tool registration with modern SDK - **`src/index.ts`** - Server class with handler methods ### Validation Features All models include: - ✅ Unique entity IDs - ✅ Valid relationship references - ✅ No orphaned relationships - ✅ Proper multiplicity definitions - ✅ Type-safe attributes and methods ## 🛠️ Created With These examples were created using: - **MCP Server**: system-designer-mcp v1.0.0 - **MCP SDK**: @modelcontextprotocol/sdk v1.18.2 - **Validation**: Zod v4.1.11 - **Runtime**: Bun JavaScript Runtime - **Creation Date**: 2025-09-30 - **Last Updated**: 2025-09-30 - **Tools Used**: All 6 MCP tools - `create_mson_model` - Create and validate MSON models - `validate_mson_model` - Validate model consistency - `generate_uml_diagram` - Generate PlantUML and Mermaid diagrams - `export_to_system_designer` - Export to System Designer format - `create_system_runtime_bundle` - Create System Runtime bundles - `validate_system_runtime_bundle` - Validate runtime bundles ## 🎓 Learning Resources - **PROMPTS.md** - Natural language prompts used to create these examples - **README.md** (this file) - Comprehensive documentation - **Main README** - Project overview and setup instructions - **System Runtime Docs** - <https://designfirst.io/systemruntime/> - **PlantUML Docs** - <https://plantuml.com/> - **Mermaid Docs** - <https://mermaid.js.org/> ## 🤝 Contributing Want to add more examples? Follow these steps: 1. Create a new MSON model JSON file 2. Add it to the `scripts/generate-examples.ts` script 3. Run `bun run scripts/generate-examples.ts` 4. Document the natural language prompt in `PROMPTS.md` 5. Update this README with the new example 6. Submit a pull request All examples must be generated using the actual MCP server tools - no manual file creation! ## 📄 License These examples are provided as-is for educational and demonstration purposes.