Content
[](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
