System Designer MCP Server

A Model Context Protocol (MCP) server that provides AI agents with tools to create, validate, and export UML system models. Built with a tool-based approach that empowers LLMs rather than trying to replace their natural language understanding capabilities.

📚 Documentation

• API Reference - Detailed API documentation for all MCP tools
• CLI Guide - Command-line interface usage and examples
• Integration Guide - Platform integration instructions
• Examples - Sample models and use cases

Features

Core 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

Key Capabilities

• ✅ Tool-Based Architecture: LLMs handle understanding, server handles validation/formatting
• ✅ Type Safety: Comprehensive Zod schema validation for all inputs and outputs
• ✅ Multiple UML Formats: Support for both PlantUML and Mermaid diagram generation
• ✅ System Designer Integration: Direct export to System Designer macOS application
• ✅ Comprehensive Testing: Full test coverage for all tools and functionality

Installation

Prerequisites

• Bun JavaScript runtime
• Node.js compatibility through Bun

Setup

# Clone the repository
git clone <repository-url>
cd system-designer-mcp

# Install dependencies
bun install

# Build the project
bun run build

# Run tests
bun test

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd system-designer-mcp

# Install dependencies
bun install

# Build the project
bun run build

# Run tests
bun test

Using the MCP Server

1. Start the server:

bun run dev

2. 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',
});

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
• 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

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

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

# 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/
├── index.ts                    # Main MCP server with all tools
├── cli.ts                      # Command-line interface
└── integration/
    └── system-designer.ts     # System Designer app integration

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

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

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

Contributing

This project follows a simple contribution model:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

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